Extra Logins API

The Extra Logins API allows users to purchase, manage, and gift additional login slots for their accounts. This feature enables users to connect more devices simultaneously to the VPN service.

Overview

The API provides several key operations:

• Purchase Extra Logins
• Gift Extra Logins
• View Active Extra Logins
• Calculate Price with Discounts
• Manage Extra Logins Subscriptions

Flow Diagram

sequenceDiagram
    participant User
    participant API
    participant Payment
    participant Notification
    participant Radius

    User->>API: 1. Get Available Plans
    API-->>User: Return plans list
    User->>API: 2. Calculate Price
    API-->>User: Return price with discounts
    User->>API: 3. Purchase Extra Logins
    API->>Payment: Process payment
    Payment-->>API: Payment confirmed
    API->>Radius: Update login count
    API->>Notification: Send confirmation
    Notification-->>User: Confirmation email/SMS
    API-->>User: Return success

API Reference

Query Available Plans

Retrieves available extra login plans.

query ExtraLoginPlans($type: String) {
  extraLoginPlans(type: $type) {
    id
    name
    description
    loginCount
    basePrice
    durationDays
    subscription
    giftable
    bulkDiscountPercent
    minimumQuantity
  }
}

Response

{
  "data": {
    "extraLoginPlans": [
      {
        "id": "1",
        "name": "Basic Extra Logins",
        "description": "Add 2 more device connections",
        "loginCount": 2,
        "basePrice": 9.99,
        "durationDays": 30,
        "subscription": false,
        "giftable": true,
        "bulkDiscountPercent": 10.0,
        "minimumQuantity": 2
      }
    ]
  }
}

Calculate Price

Calculates the final price including any applicable discounts (loyalty, bulk).

query CalculateExtraLoginPrice($planId: ID!, $quantity: Int!) {
  calculateExtraLoginPrice(planId: $planId, quantity: $quantity) {
    basePrice
    loyaltyDiscount
    bulkDiscount
    finalPrice
    currency
  }
}

Variables

{
  "planId": "1",
  "quantity": 2
}

Purchase Extra Logins

Initiates a purchase of extra logins.

mutation PurchaseExtraLogins(
  $planId: ID!
  $quantity: Int!
  $paymentMethod: String!
  $selectedCoin: String
) {
  purchaseExtraLogins(
    planId: $planId
    quantity: $quantity
    paymentMethod: $paymentMethod
    selectedCoin: $selectedCoin
  ) {
    paymentId
    clientSecret
    checkoutUrl
    status
    message
    requiresAction
    amount
    currency
  }
}

Variables

{
  "planId": "1",
  "quantity": 2,
  "paymentMethod": "STRIPE",
  "selectedCoin": null
}

Gift Extra Logins

Sends extra logins as a gift to another user.

mutation GiftExtraLogins($planId: ID!, $recipientEmail: String!) {
  giftExtraLogins(planId: $planId, recipientEmail: $recipientEmail)
}

Variables

{
  "planId": "1",
  "recipientEmail": "friend@example.com"
}

View User's Extra Logins

Retrieves active extra logins for the current user.

query UserExtraLogins {
  userExtraLogins {
    id
    planName
    loginCount
    startDate
    expiryDate
    active
    subscription
    giftedByEmail
  }
}

Cancel Subscription

Cancels an active extra logins subscription.

mutation CancelExtraLoginSubscription($subscriptionId: String!) {
  cancelExtraLoginSubscription(subscriptionId: $subscriptionId)
}

Implementation Guide

Purchase Flow

1. Fetch available plans:

const response = await client.query({
  query: gql`
    query GetPlans {
      extraLoginPlans(type: "regular") {
        id
        name
        loginCount
        basePrice
      }
    }
  `,
});

2. Calculate price with discounts:

const priceResponse = await client.query({
  query: gql`
    query GetPrice($planId: ID!, $quantity: Int!) {
      calculateExtraLoginPrice(planId: $planId, quantity: $quantity) {
        basePrice
        finalPrice
        currency
      }
    }
  `,
  variables: {
    planId: selectedPlan.id,
    quantity: selectedQuantity,
  },
});

3. Process purchase:

const purchaseResponse = await client.mutate({
  mutation: gql`
    mutation Purchase($planId: ID!, $quantity: Int!, $paymentMethod: String!) {
      purchaseExtraLogins(
        planId: $planId
        quantity: $quantity
        paymentMethod: $paymentMethod
      ) {
        paymentId
        clientSecret
        status
      }
    }
  `,
  variables: {
    planId: selectedPlan.id,
    quantity: selectedQuantity,
    paymentMethod: "STRIPE",
  },
});

Best Practices

1. Validation

   • Verify user authentication
   • Validate quantity limits
   • Check payment method availability
   • Verify recipient email for gifts

2. Error Handling

   • Handle payment failures gracefully
   • Validate plan availability
   • Check subscription status
   • Verify user limits

3. Security

   • Implement rate limiting
   • Verify payment confirmations
   • Validate gift recipients
   • Check user permissions

Error Handling

Common errors and their resolutions:

Error Code	Description	Resolution
PLAN_NOT_FOUND	Selected plan doesn't exist	Refresh plans list
INVALID_QUANTITY	Quantity below minimum or above maximum	Adjust quantity
PAYMENT_FAILED	Payment processing failed	Retry with different method
INVALID_RECIPIENT	Gift recipient not found	Verify email address
LIMIT_EXCEEDED	User reached maximum allowed logins	Contact support

Rate Limiting

• Purchase requests: 5 per hour
• Price calculations: 20 per minute
• Gift operations: 3 per hour
• Plan queries: 60 per minute

Webhooks

The API sends webhook events for:

• EXTRA_LOGINS_PURCHASED
• EXTRA_LOGINS_GIFTED
• EXTRA_LOGINS_EXPIRED
• EXTRA_LOGINS_CANCELLED

Example webhook payload:

{
  "event": "EXTRA_LOGINS_PURCHASED",
  "timestamp": "2024-11-17T12:30:00Z",
  "data": {
    "userId": "123",
    "planId": "1",
    "quantity": 2,
    "loginCount": 4,
    "expiryDate": "2024-12-17T12:30:00Z"
  }
}

Security Considerations

• All mutations require authentication
• Gift operations verify recipient existence
• Payment confirmations are verified server-side
• Login counts are validated against user limits
• Subscription changes are transactional
• Rate limiting prevents abuse
• Webhook signatures are verified

Notifications

The system sends notifications for:

• Purchase confirmation
• Gift received
• Expiration reminders (7, 3, 1 days before)
• Subscription cancellation
• Login count updates